docs(billing/crons): jitter & sharding guidance#3579
Conversation
|
Warning Rate limit exceeded
To keep reviews running without waiting, you can enable usage-based add-on for your organization. This allows additional reviews beyond the hourly cap. Account admins can enable it under billing. ⌛ How to resolve this issue?After the wait time has elapsed, a review can be triggered using the We recommend that you space out your commits to avoid hitting the rate limit. 🚦 How do rate limits work?CodeRabbit enforces hourly rate limits for each developer per organization. Our paid plans have higher rate limits than the trial, open-source and free plans. In all cases, we re-allow further reviews after a brief timeout. Please see our FAQ for further information. ℹ️ Review info⚙️ Run configurationConfiguration used: Path: .coderabbit.yaml Review profile: ASSERTIVE Plan: Pro Run ID: 📒 Files selected for processing (1)
WalkthroughDocumentation added to the billing crons module describing jitter and sharding strategies to mitigate thundering-herd effects. Covers startup jitter implementation, sharding criteria (tenant count threshold, single-table contention), example patterns, and constraints on jitter magnitude and applicability. ChangesCron Operational Guidance
Estimated code review effort🎯 1 (Trivial) | ⏱️ ~5 minutes 🚥 Pre-merge checks | ✅ 4 | ❌ 1❌ Failed checks (1 inconclusive)
✅ Passed checks (4 passed)
✏️ Tip: You can configure your own custom pre-merge checks in the settings. ✨ Finishing Touches🧪 Generate unit tests (beta)
Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out. Review rate limit: 0/1 reviews remaining, refill in 45 minutes and 30 seconds.Comment |
Up to standards ✅🟢 Issues
|
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 1
🤖 Prompt for all review comments with AI agents
Verify each finding against the current code and only fix it if needed.
Inline comments:
In `@modules/billing/crons/README.md`:
- Around line 62-70: The README snippet claims jitter is "persisted across
restarts" but the example computes jitter with Math.random() on process start
(jitterMs) which re-randomizes on every restart; update the doc so the code and
text match by either (A) changing the prose to state the jitter is re-randomized
each restart, or (B) replace the Math.random() example with a
deterministic/persisted jitter derivation (e.g., derive jitterMs from a stable
pod identity like process.env.HOSTNAME via a small stable hash) and keep the
rest of the example using cron.schedule and BillingResetService.resetAllDue;
ensure you reference jitterMs, cron.schedule and BillingResetService.resetAllDue
in the updated snippet so readers can locate the change.
🪄 Autofix (Beta)
Fix all unresolved CodeRabbit comments on this PR:
- Push a commit to this branch (recommended)
- Create a new PR with the fixes
ℹ️ Review info
⚙️ Run configuration
Configuration used: Path: .coderabbit.yaml
Review profile: ASSERTIVE
Plan: Pro
Run ID: 22f28da3-ca1f-4781-b916-a0ad73177214
📒 Files selected for processing (1)
modules/billing/crons/README.md
![codacy-production[bot]](https://avatars.githubusercontent.com/in/56611?s=60&v=4){kind=small}
There was a problem hiding this comment.
Pull Request Overview
While this PR meets basic quality standards, there are significant architectural conflicts in the documentation that should be resolved before merging. The primary concern is the suggestion to use an internal application scheduler (cron.schedule) inside a script intended for execution by an external orchestrator like Kubernetes. This creates a risk of hung processes or missed executions.
Additionally, the documentation contains a technical inaccuracy regarding jitter persistence. In the ephemeral context of Kubernetes CronJobs, the provided code will not persist jitter across restarts. Refinement of these examples is necessary to provide safe and actionable guidance for production systems.
About this PR
- There is a systemic inconsistency between the deployment model (external K8s CronJob) and the implementation examples (internal Node.js scheduler). The documentation should consistently promote patterns suitable for ephemeral, orchestrator-triggered tasks.
Test suggestions
- Verify that the suggested jitter logic (setTimeout) does not exceed the documented idempotency window constraints.
- Verify that sharding guidance provides specific actionable thresholds (e.g., 10k tenants).
TIP Improve review quality by adding custom instructions
TIP How was this review? Give us feedback
There was a problem hiding this comment.
Pull request overview
This PR adds operational guidance to the billing cron documentation, explaining how downstream consumers can reduce burst load when running the module’s standalone billing cron scripts across many deployments. It fits the codebase by extending the billing module’s CronJob-oriented README without changing runtime behavior.
Changes:
- Adds a new Jitter & sharding section to the billing cron README.
- Documents a startup-jitter example, a heuristic for when to shard work, and constraints around jitter windows.
- Clarifies that the scheduler snippet is illustrative and that billing crons are otherwise documented as Kubernetes CronJobs.
- Remove misleading "persisted across restarts" prose — K8s CronJob scripts are invoked once per execution, so jitter is naturally per-invocation - Replace cron.schedule() snippet (no-cron-dep model) with a self-executing top-level await delay pattern matching the actual entrypoint structure - Add optional stable per-pod jitter derivation from HOSTNAME hash - Add SHARD_INDEX/SHARD_TOTAL env-var example in CronJob manifest + script filter snippet to complete sharding implementation guidance
…e hash $where executes JS in MongoDB and is deprecated/disabled in newer versions. Replace with a client-side hash on _id strings — same O(n) complexity, no server-side JS dependency.
…lability note - Wrap jitter snippet in async IIFE (CJS entrypoints don't support top-level await) - Rename stable-jitter variables (hostHash/stableJitterMs) to avoid const redeclaration if both snippets appear in the same file - Add scalability caveat on in-memory shard filter; point toward server-side $mod for high tenant counts
Summary
modules/billing/crons/README.md, inserted after the Kubernetes CronJob example and before themeterModedependency section.cron.schedulesnippet is illustrative (nonode-crondep in devkit).Devkit-shipped crons run identical UTC schedules across all consumer deployments — without jitter, N consumers fan-in to one DB burst. This is documentation-only guidance; no code changes.
Test plan
Summary by CodeRabbit